This will be used in the future for things like cache configuration.
Adding now as it is a breaking change.

Although this doesn't provide immediate benefit, the intent is to make
the data decoder available separately in a future commit for public use.

This further decouples the code. There are probably future improvements
for reducing redundancy however.

This is largely based on #91.

Extend the UnmarshalMaxMindDB interface to work recursively with nested
types, matching the behavior of encoding/json's UnmarshalJSON. Custom
unmarshalers are now called for:

- Struct fields that implement Unmarshaler
- Pointer fields (creates value if nil, then checks for Unmarshaler)
- Slice elements that implement Unmarshaler
- Map values that implement Unmarshaler

This enhancement allows for more flexible custom decoding strategies in
complex data structures, improving performance optimization opportunities
for nested types.

Add PeekType() method to Decoder that returns the type of the current value
without consuming it, similar to jsontext.Decoder.PeekKind(). This enables
look-ahead parsing for conditional decoding logic.

The method follows pointers to return the actual data type being pointed to
rather than just returning TypePointer.

The Decoder and Unmarshaler types are now available in the mmdbdata
package for applications that need direct access to the decoding API.

Renames Type* constants to Kind* and PeekType() to PeekKind()
throughout the codebase to match Go's encoding/json/v2 naming
conventions. This improves API consistency with the standard
library.

Renames all Decoder methods from Decode* to Read* (e.g.,
DecodeString to ReadString) to match Go's encoding/json/v2
jsontext.Decoder naming conventions. This improves API
consistency with the standard library.

Adds DecoderOption type and variadic options parameter to enable future
configuration without breaking API changes. Follows existing library
patterns like ReaderOption and NetworksOption.

Improved error messages to include byte offset information and, for the
reflection-based API, path information for nested structures using JSON
Pointer format. For example, errors may now show "at offset 1234, path
/city/names/en" or "at offset 1234, path /list/0/name" instead of just the
underlying error message.

The implementation maintains zero allocation on the happy path through
retroactive path building during error unwinding.

Replaces unbounded cache with fixed 512-entry array using offset-based
indexing. Provides 15% performance improvement while preventing memory
growth and ensuring thread safety for concurrent reader usage.

Move size validation logic to DataDecoder to eliminate duplication
and create single source of truth for data validation.

And make them more accurate.

- Add comprehensive field documentation to Metadata struct with
  references to MaxMind DB specification
- Add BuildTime() convenience method to convert BuildEpoch to time.Time
- Enhance Verify() documentation explaining validation scope and use cases
- Add ExampleReader_Verify showing verification and metadata access
- Add TestMetadataBuildTime to verify BuildTime() method correctness

Add makeTestName helper function to create reasonable test names from
long hex strings. TestDecodeByte and TestDecodeString now show concise
names like '9e06b37878787878...7878' instead of extremely long hex
strings that made test output unreadable.

Remove the experimental deserializer interface and all supporting code:
- Delete deserializer.go interface definition
- Delete deserializer_test.go test file
- Remove deserializer support from reflection.go
- Remove deserializer methods from data_decoder.go
- Remove unused math/big import from data_decoder.go
- Add breaking change notice to changelog recommending UnmarshalMaxMindDB

Error messages for type mismatches now display readable type names like
'Map' and 'Slice' instead of numeric codes, making debugging easier.

Make StringCache, buffer access, InternAt, and all DataDecoder methods
package-private since they are only used within the decoder package.
Keeps Kind methods public as they are exposed via mmdbdata type alias.

Replaces global mutex with per-entry mutexes to reduce allocation
count from 33 to 10 per operation in downstream libraries while
maintaining thread safety and good concurrent performance.

Add BenchmarkCityLookupConcurrent to demonstrate string cache performance
improvements under concurrent load. Tests 1, 4, 16, and 64 goroutines
performing realistic city lookups, providing clear metrics for concurrent
scaling behavior.

Use direct type assertion instead of reflection-based interface
checking in Decode method for better performance.

Replace nodeReader interface with specialized traverseTree functions
for each record size. Eliminates interface dispatch overhead and
implements branchless offset calculations for improved performance.

Replace reflect.Type.Implements() with type assertion using comma-ok
idiom and remove redundant pointer interface check. The recursive
decode call handles pointer receiver implementations via CanAddr().

Eliminates unmarshalerType variable and reduces code complexity while
maintaining identical functionality and performance.

Remove inaccurate 15% performance improvement claim that was
contradicted by benchmark testing. Add missing BREAKING CHANGE
label for network options API changes.

This commit implements encoding/json/v2 style field precedence rules
for struct field resolution, replacing the previous two-phase
processing with a single-phase approach that properly handles field
conflicts using depth-based and tag-based precedence.

Key changes:
- Replace fieldsType.anonymousFields with fieldInfo metadata structure
- Implement breadth-first traversal for field collection with depth tracking
- Add support for embedded pointer types (*EmbeddedStruct)
- Apply json/v2 precedence rules: shallow beats deep, tagged beats untagged
- Use single-phase processing with FieldByIndex for embedded field access
- Initialize nil embedded pointers during field traversal

Precedence rules applied:
1. Shallowest embedding depth wins
2. Among same depth, explicitly tagged field wins over untagged
3. Among same depth and tag status, first declared wins

Fixes embedded pointer field access that was causing nil pointer
dereferences in complex nested structures.

Adds basic validation for maxminddb struct tags inspired by
encoding/json/v2's tag validation approach. Currently validates:

- UTF-8 encoding of tag values
- Provides foundation for future tag validation improvements

The validation is designed to be non-intrusive - validation errors
are currently ignored to maintain backward compatibility, but the
infrastructure is in place for future enhancements.

This follows the json/v2 pattern of catching obvious user mistakes
while being permissive about edge cases that might be legitimate.

Implement field index reindexing and addressable value wrapper to
reduce reflection overhead. Split field indices for faster access
and eliminate redundant bounds checks during field traversal.

Based on encoding/json/v2 optimizations for better performance in
struct field access patterns.

Optimizes the reflection-based decoder with more efficient
field access patterns and reduced memory allocations.
Eliminates duplicate code paths and unused functions.

Performance improvement measured in geoip2-golang benchmarks.

Update ReadMap and ReadSlice to return collection size along with
iterators, enabling efficient pre-allocation of maps and slices.
Iterator remains the primary return value for natural usage patterns.